## 4.12. Manual Pages

The most empowering information you can get is how to conduct your own research. Following this precept, we'll now tell you about the online help system that comes built in to Unix systems. It is called manual pages, or man pages for short.

Actually, manual pages are not quite the boon they ought to be. This is because they are short and take a lot of Unix background for granted. Each one focuses on a particular command and rarely helps you decide why you should use that command. Still, they are critical. Commands can vary slightly on different Unix systems, and the manual pages are the most reliable way to find out what your system does. The Linux Documentation Project deserves a lot of credit for the incredible number of hours they have put into creating manual pages. To find out about a command, enter a command like:

>     $ man ls

Manual pages are divided into different sections depending on what they are for. User commands are in section 1, Unix system calls in section 2, and so on. The sections that will interest you most are 1, 5 (file formats), and 8 (system administration commands). When you view man pages online, the section numbers are conceptual; you can optionally specify them when searching for a command:

>     $ man 1 ls

But if you consult a hard-copy manual, you'll find it divided into actual sections according to the numbering scheme. Sometimes an entry in two different sections can have the same name. (For instance, `chmod` is both a command and a system call.) So you will sometimes see the name of a manual page followed by the section number in parentheses, as in `ls(1)`.

There is one situation in which you will need the section number on the command line: when there are several manual pages for the same keyword (e.g., one for a command with that name and one for a system function with the same name). Suppose you want to look up a library call, but the `man` shows you the command because its default search order looks for the command first. In order to see the manual page for the library call, you need to give its section number.

Look near the top of a manual page. The first heading is `NAME`. Under it is a brief one-line description of the item. These descriptions can be valuable if you're not quite sure what you're looking for. Think of a word related to what you want, and specify it in an `apropos` command:

>     $ apropos edit

The previous command shows all the manual pages that have something to do with editing. It's a very simple algorithm: `apropos` simply prints out all the `NAME` lines that contain the string you ask for.

An X Window System application, `xman`, also helps you browse manual pages. It is described in the section "Section 11.4.9, "xman: A Point-and-Click Interface to Manual Pages"" in Chapter 11, "Customizing Your X Environment".

Like commands, manual pages are sometimes installed in strange places. For instance, you may install some site-specific programs in the directory /usr/local, and put their manual pages in /usr/local/man. The `man` command will not automatically look in /usr/local/man, so when you ask for a manual page you may get the message "No manual entry." Fix this by specifying all the top man directories in a variable called MANPATH. For example (you have to put in the actual directories where the manual pages are on your system):

>     $ export MANPATH=/usr/man:/usr/local/man

The syntax is like PATH, described earlier in this chapter. Each two directories are separated by a colon. If your shell is `csh` or `tcsh`, you need to say:

>     $ setenv MANPATH /usr/man:/usr/local/man

Have you read some manual pages and still found yourself confused? They're not meant to be introductions to new topics. Get yourself a good beginner's book about Unix, and come back to manual pages gradually as you become more comfortable on the system; then they'll be irreplaceable.

Manual pages are not the only source of information on Unix systems. Programs from the GNU project often have Info pages that you read with the program `info`. For example, to read the Info pages for the command `find`, you would enter:

>     info find

The `info` program is arcane and has lots of navigation features; to learn it, your best bet will be to type Ctrl-H in the `info` program and read through the help screen. Fortunately, there are also programs that let you read Info pages more easily, notably `tkinfo` and `kdehelp`. These commands use the X Window System to present a graphical interface. You can also read Info pages from Emacs (see the section "Section 9.2, "The Emacs Editor"" in Chapter 9, "Editors, Text Tools, Graphics, and Printing") or use the command `pinfo` available on some Linux distributions that works more like the Lynx web browser.

In recent times, more and more documentation is provided in the form of HTML pages. You can read those with any web browser (see Chapter 16, "The World Wide Web and Electronic Mail"). For example, in Netscape Navigator, you select "Open Page..." from the "File" menu and press the "Choose File" button, which opens an ordinary file selection dialog where you can select your documentation file.

Copyright © 2001 O'Reilly & Associates. All rights reserved.